package com.ldodds.ot;

/**
 * An identifiable object.
 * 
 * <h2>Background</h2>
 * <p>
 * A resource exposed through a web application can be thought to have two different 
 * logical identifiers: an internal primary identifier used within the application's 
 * data model (e.g. a primary key) and an external identifier used to link to the resource 
 * within the website.
 * </p>
 * <p>
 * In a semantic web application the "internal" identifier will be the URI of an RDF resource.
 * The "web" identifier will be a relative URI that is resolved within the context of the 
 * application. In some scenarios these two identifiers may be the same, e.g. where a resource 
 * is being exposed using Linked Data principles, and human and machine-readable interfaces 
 * are delivered through content negotiation. E.g. the identifier for a person may be 
 * <code>http://www.example.org/person/1</code>. Dereferencing this within a browser may result in the 
 * delivery of an HTML document, whereas a semantic web agent may receive RDF/XML. In some 
 * cases a redirect may be used to direct the user agent to a specific location, e.g. <code>/person/1.html</code> 
 * but all links are typically directed to the "web" form of the identifier, e.g. <code>/person/1</code>.
 * </p>
 * <p>
 * However, in some cases, e.g. when creating a data browsing application over some externally 
 * sourced RDF data, the two URLs may differ, e.g. the resource URI may be <code>http://www.example.org/person/1</code>  
 * whereas the web identifier for the resource may be <code>http://www.example.com/person/1</code>, or 
 * <code>/person/1</code>, when expressed as a relative URL linking from with the web application. 
 * </p>
 * <p>
 * In the latter case the two URIs may be radically different and cannot be easily derived from one another.
 * </p>
 * <p>
 * Irrespective of which model is in play within a specific application, this interface takes the approach 
 * that the basic assumption, of having two identifiers, holds for all applications. The two methods on this 
 * interface provide direct access to those two identifiers.
 * </p>
 * @author Leigh Dodds
 */
public interface Identifiable {
	
	/**
	 * Retrieve the primary identifier for this resource. This is used to identify the resource within 
	 * the applications' dataset. The precise relationship between this identifier, and the corresponding 
	 * web identifier may is undefined (see above comments).
	 * 
	 * @return the resources identifier
	 */
	public String getIdentifier();
	
	/**
	 * Retrieve the web identifier for this resource. This is used to link to the resource from within a web application, 
	 * e.g. to generate a link to the resource from a templated web page. The precise relationship between the 
	 * web identifier, and the corresponding primary identifier is undefined (see above comments).
	 * 
	 * @return the resources web identifier
	 */
	public String getWebIdentifier();
}
